Frameworks/Adium Framework/NSString+NDUtilities.h

   1 /*!
   2         @header NSString+NDUtilities
   3         @abstract Defines the category <tt>NSString+NDUtilities</tt>
   4         @discussion Additonal useful methods for <tt>NSString</tt>, that can be used in general situations.
   5   */
   6
   7 #import <Foundation/Foundation.h>
   8
   9 /*!
  10         @category NSString(NDUtilities)
  11         @abstract Addition methods for <tt>NSString</tt>
  12         @discussion Additonal useful methods for <tt>NSString</tt>, that can be used in general situations. see also NSString(NDContainsCharacterExtension), NSString(NDPathExtensions) and NSString(CarbonUtilitiesPaths).
  13  */
  14 @interface NSString (NDUtilities)
  15
  16 /*!
  17         @method stringWithNonLossyASCIIString:
  18         @abstract Create a <tt>NSString</tt>.
  19         @discussion Creates a <tt>NSString</tt> from <tt>NSNonLossyASCIIStringEncoding</tt> encoding, a 7-bit verbose ASCII to represent all Unicode characters
  20         @param ASCIIString A 7 bit ASCII string in <tt>NSNonLossyASCIIStringEncoding</tt> encoding.
  21         @result A new <tt>NSString</tt>
  22  */
  23 + (id)stringWithNonLossyASCIIString:(const char *)ASCIIString;
  24
  25 /*!
  26         @method stringWithFormat:arguments:
  27         @abstract Create a <tt>NSString</tt>.
  28         @discussion Creates a new string object, using <tt><i>format</i></tt> as a template into which the following <tt><i>argList</i></tt> values are substituted. Raises an <tt>NSInvalidArgumentException</tt> if <tt><i>format</i></tt> is <tt>nil</tt>.
  29         @param format The template string.
  30         @param argList The arguments to be inserted into <tt><i>format</i></tt>
  31         @result A new <tt>NSString</tt>
  32  */
  33 + (id)stringWithFormat:(NSString *)format arguments:(va_list)argList;
  34
  35 /*!
  36         @method initWithNonLossyASCIIString:
  37         @abstract Intialise a <tt>NSString</tt>.
  38         @discussion Initialises a <tt>NSString</tt> from <tt>NSNonLossyASCIIStringEncoding</tt> encoding, a 7-bit verbose ASCII to represent all Unicode characters.
  39         @param ASCIIString A 7 bit ASCII string in <tt>NSNonLossyASCIIStringEncoding</tt> encoding.
  40         @result A initialised <tt>NSString</tt>.
  41  */
  42 - (id)initWithNonLossyASCIIString:(const char *)ASCIIString;
  43
  44 /*!
  45         @method nonLossyASCIIString
  46         @abstract Get a 7 bit ASCII representation of a <tt>NSString</tt> containing Unicode characters.
  47         @discussion Returns a c string using <tt>NSNonLossyASCIIStringEncoding</tt> encoding, a 7-bit verbose ASCII to represent all Unicode characters. The returned C string will be automatically freed just as a returned object would be released; your code should copy the C string, if it needs to store the C string outside of the autorelease context in which the C string is created.
  48         @result A c string with <tt>NSNonLossyASCIIStringEncoding</tt> encoding.
  49  */
  50 - (const char *)nonLossyASCIIString;
  51
  52 /*!
  53         @method isCaseInsensitiveEqualToString:
  54         @abstract Test if a string is case insensitive equivelent.
  55         @discussion Returns <tt>YES</tt> if string is case insensitive equivalent to the receiver (if they have the same <tt>id</tt> or if they are <tt>NSOrderedSame</tt> in a litereral, case insensitive comparison), <tt>NO</tt> otherwise. .
  56         @param string The string to compare with.
  57         @result Returns <tt>YES</tt> string are equivelent <tt>NO</tt>.
  58  */
  59 - (BOOL)isCaseInsensitiveEqualToString:(NSString *)string;
  60
  61 /*!
  62         @method hasCaseInsensitivePrefix:
  63         @abstract Test prefix.
  64         @discussion Returns <tt>YES</tt> if <tt><i>string</i></tt> case insensitive matches the beginning characters of the receiver, <tt>NO</tt> otherwise. Returns <tt>NO</tt> if <tt><i>string</i></tt> is the <tt>nil</tt> string or empty. This method is a convenience for comparing strings using the <tt>NSAnchoredSearch</tt> option. See "Strings" for more information.
  65         @param string The string to check for.
  66         @result Returns <tt>YES</tt> if has case insensitive prefix <tt><i>string</i></tt>.
  67  */
  68 - (BOOL)hasCaseInsensitivePrefix:(NSString *)string;
  69
  70 /*!
  71         @method hasCaseInsensitiveSuffix:
  72         @abstract Test suffix.
  73         @discussion Returns <tt>YES</tt> if <tt><i>string</i></tt> case insensitive matches the ending characters of the receiver, <tt>NO</tt> otherwise. Returns <tt>NO</tt> if <tt><i>string</i></tt> is the <tt>nil</tt> string or empty. This method is a convenience for comparing strings using the <tt>NSAnchoredSearch</tt> and <tt>NSBackwardsSearch</tt> options. See "Strings" for more information.
  74         @param string The string to check for.
  75         @result Returns <tt>YES</tt> if has case insensitive suffix <tt><i>string</i></tt>.
  76  */
  77 - (BOOL)hasCaseInsensitiveSuffix:(NSString *)string;
  78
  79 /*!
  80         @method containsString:
  81         @abstract Test if a string contains a substring.
  82         @discussion Invokes <tt>containsString:options:</tt> with no options. Raises an <tt>NSInvalidArgumentException</tt> if string is <tt>nil</tt>.
  83         @param subString The string to search for.
  84         @result Returns <tt>YES</tt> if substring found otherwise <tt>NO</tt>.
  85  */
  86 - (BOOL)containsString:(NSString *)subString;
  87
  88 /*!
  89         @method containsString:options:
  90         @abstract Test if a string contains a substring.
  91         @discussion Invokes <tt>containsString:options:range:</tt> with the options specified by <tt><i>mask</i></tt> and the entire extent of the receiver as the range. Raises an <tt>NSInvalidArgumentException</tt> if any of the arguments are <tt>nil</tt>.
  92         @param subString The string to search for.
  93         @param mask Mask values determining how to search.
  94         @result Returns <tt>YES</tt> if substring found otherwise <tt>NO</tt>.
  95  */
  96 - (BOOL)containsString:(NSString *)subString options:(unsigned)mask;
  97
  98 /*!
  99         @method containsString:options:range:
 100         @abstract Test if a string contains a substring.
 101         @discussion Returns <tt>YES</tt> if <tt><i>subString</i></tt> occurs within range in the receiver. If <tt><i>subString</i></tt> isn't found, returns a <tt>NO</tt>. The following options may be specified in <tt><i>mask</i></tt> by combining them with the C bitwise OR operator:
 102                                 <blockquote><table border = "1" width = "90%">
 103                                         <thead><tr><th>Search Option</th><th>Effect</th></tr></thead>
 104                                         <tr><td align = "center"><tt>NSCaseInsensitiveSearch</tt></td><td>Ignores case distinctions among characters.</td></tr>
 105                                         <tr><td align = "center"><tt>NSLiteralSearch</tt></td><td>Performs a byte-for-byte comparison. Differing literal sequences (such as composed character sequences) that would otherwise be considered equivalent are considered not to match. Using this option can speed some operations dramatically.</td></tr>
 106                                         <tr><td align = "center"><tt>NSBackwardsSearch</tt></td><td>Performs searching from the end of the range toward the beginning.</td></tr>
 107                                         <tr><td align = "center"><tt>NSAnchoredSearch</tt></td><td>Performs searching only on characters at the beginning or end of the range. No match at the beginning or end means nothing is found, even if a matching sequence of characters occurs elsewhere in the string.</td></tr>
 108                                 </table></blockquote>
 109
 110                         Raises an NSRangeException if any part of range lies beyond the end of the string.
 111         @param subString The string to search for.
 112         @param mask Mask values determining how to search.
 113         @param range The range within the string to search.
 114         @result Returns <tt>YES</tt> if substring found otherwise <tt>NO</tt>.
 115  */
 116
 117 - (BOOL)containsString:(NSString *)subString options:(unsigned)mask range:(NSRange)range;
 118
 119 /*!
 120         @method indexOfCharacter:range:
 121         @abstract Get the index of a character.
 122         @discussion Returns the index of the first occurance of the character <tt><i>character</i></tt> within the range <tt><i>range</i></tt>, if the receiver does not contain the character within the range then <tt>NSNotFound</tt> is return.
 123         @param character The character to look for.
 124         @param range The range to limit the search to.
 125         @result Returns the index of the character or <tt>NSNotFound</tt> if not found.
 126  */
 127 - (unsigned int)indexOfCharacter:(unichar)character range:(NSRange)range;
 128
 129
 130 /*!
 131         @method indexOfCharacter:
 132         @abstract Get the index of a character.
 133         @discussion Returns the index of the first occurance of the character <tt><i>character</i></tt>, if the receiver does not contain the character then <tt>NSNotFound</tt> is return.
 134         @param character The character to look for.
 135         @result Returns the index of the character or <tt>NSNotFound</tt> if not found.
 136  */
 137 - (unsigned int)indexOfCharacter:(unichar)character;
 138
 139 /*!
 140         @method containsCharacter:
 141         @abstract Test if a string contains a character.
 142         @discussion Returns <tt>YES</tt> if the receiver contains the character <tt><i>character</i></tt>, otherwise returns <tt>NO</tt>.
 143         @param character The character to look for.
 144         @result Returns <tt>YES</tt> if the receiver contains the character.
 145  */
 146 - (BOOL)containsCharacter:(unichar)character;
 147
 148 /*!
 149         @method containsCharacter:range:
 150         @abstract Test if a string contains a character.
 151         @discussion Returns <tt>YES</tt> if the receiver contains the character <tt><i>character</i></tt> within the range <tt><i>range</i></tt>, otherwise returns <tt>NO</tt>.
 152         @param character The character to look for.
 153         @param range The range to limit the search to.
 154         @result Returns <tt>YES</tt> if the receiver contains the character.
 155  */
 156 - (BOOL)containsCharacter:(unichar)character range:(NSRange)range;
 157
 158 /*!
 159         @method containsAnyCharacterFromSet:
 160         @abstract Test if a string contains a character from a set.
 161         @discussion Returns <tt>YES</tt> if the receiver contains any character within <tt><i>set</i></tt>, otherwise returns <tt>NO</tt>.
 162         @param set The set of characters to look for.
 163         @result Returns <tt>YES</tt> if the receiver contains any of the characters.
 164  */
 165 - (BOOL)containsAnyCharacterFromSet:(NSCharacterSet *)set;
 166
 167 /*!
 168         @method containsAnyCharacterFromSet:options:
 169         @abstract Test if a string contains a character from a set.
 170         @discussion Returns <tt>YES</tt> if the receiver contains any character within <tt><i>set</i></tt> within the range <tt><i>range</i></tt>, otherwise returns <tt>NO</tt>. The following options may be specified in <tt><i>mask</i></tt> by combining them with the C bitwise OR operator:
 171         <blockquote><blockquote><table border = "1" width = "90%">
 172                 <thead>
 173                         <th>Search Option</th>
 174                         <th>Effect</th>
 175                 </thead>
 176                 <tr>
 177                         <td align = "center"><tt>NSCaseInsensitiveSearch</tt></td>
 178                         <td>Ignores case distinctions among characters.</td>
 179                 </tr>
 180                 <tr>
 181                         <td align = "center"><tt>NSLiteralSearch</tt></td>
 182                         <td>Performs a byte-for-byte comparison. Differing literal sequences (such as composed character sequences) that would otherwise be considered equivalent are considered not to match. Using this option can speed some operations dramatically.</td>
 183                 </tr>
 184                 <tr>
 185                         <td align = "center"><tt>NSBackwardsSearch</tt></td>
 186                         <td>Performs searching from the end of the range toward the beginning.</td>
 187                 </tr>
 188         </table></blockquote></blockquote>
 189         See "Strings" for details on these options. Raises an <tt>NSInvalidArgumentException</tt> if any of the arguments are <tt>nil</tt>.
 190         @param set The set of characters to look for.
 191         @param mask Mask values determining how to search.
 192         @result Returns <tt>YES</tt> if the receiver contains any of the characters.
 193  */
 194 - (BOOL)containsAnyCharacterFromSet:(NSCharacterSet *)set options:(unsigned int)mask;
 195
 196 /*!
 197         @method containsAnyCharacterFromSet:options:range
 198         @abstract Test if a string contains a character from a set.
 199         @discussion Returns <tt>YES</tt> if the receiver contains any character within <tt><i>set</i></tt> within the range <tt><i>range</i></tt>, otherwise returns <tt>NO</tt>. The following options may be specified in <tt><i>mask</i></tt> by combining them with the C bitwise OR operator:
 200         <blockquote><blockquote><table border = "1" width = "90%">
 201                 <thead>
 202                         <th>Search Option</th>
 203                         <th>Effect</th>
 204                 </thead>
 205                 <tr>
 206                         <td align = "center"><tt>NSCaseInsensitiveSearch</tt></td>
 207                         <td>Ignores case distinctions among characters.</td>
 208                 </tr>
 209                 <tr>
 210                         <td align = "center"><tt>NSLiteralSearch</tt></td>
 211                         <td>Performs a byte-for-byte comparison. Differing literal sequences (such as composed character sequences) that would otherwise be considered equivalent are considered not to match. Using this option can speed some operations dramatically.</td>
 212                 </tr>
 213                 <tr>
 214                         <td align = "center"><tt>NSBackwardsSearch</tt></td>
 215                         <td>Performs searching from the end of the range toward the beginning.</td>
 216                 </tr>
 217         </table></blockquote></blockquote>
 218         See "Strings" for details on these options. Raises an <tt>NSInvalidArgumentException</tt> if any of the arguments are <tt>nil</tt>. Raises an <tt>NSRangeException</tt> if any part of <tt><i>range</i></tt> lies beyond the end of the string.
 219         @param set The set of characters to look for.
 220         @param mask Mask values determining how to search.
 221         @param range The range to limit the search to.
 222         @result Returns <tt>YES</tt> if the receiver contains any of the characters.
 223  */
 224 - (BOOL)containsAnyCharacterFromSet:(NSCharacterSet *)set options:(unsigned int)mask range:(NSRange)range;
 225
 226 /*!
 227         @method containsOnlyCharactersFromSet:
 228         @abstract Test if a string contains only the characters from a set.
 229         @discussion Returns <tt>YES</tt> if the receiver contains only characters in <tt><i>set</i></tt> within <tt><i>set</i></tt>, otherwise returns <tt>NO</tt>.
 230         @param set The set of characters to look for.
 231         @result Returns <tt>YES</tt> if the receiver contains only the characters.
 232  */
 233 - (BOOL)containsOnlyCharactersFromSet:(NSCharacterSet *)set;
 234
 235 /*!
 236         @method containsOnlyCharactersFromSet:options:
 237         @abstract Test if a string contains only the characters from a set.
 238         @discussion Returns <tt>YES</tt> if the receiver contains only character from <tt><i>set</i></tt>, otherwise returns <tt>NO</tt>. The following options may be specified in <tt><i>mask</i></tt> by combining them with the C bitwise OR operator:
 239         <blockquote><blockquote><table border = "1" width = "90%">
 240                 <thead>
 241                         <th>Search Option</th>
 242                         <th>Effect</th>
 243                 </thead>
 244                 <tr>
 245                         <td align = "center"><tt>NSCaseInsensitiveSearch</tt></td>
 246                         <td>Ignores case distinctions among characters.</td>
 247                 </tr>
 248                 <tr>
 249                         <td align = "center"><tt>NSLiteralSearch</tt></td>
 250                         <td>Performs a byte-for-byte comparison. Differing literal sequences (such as composed character sequences) that would otherwise be considered equivalent are considered not to match. Using this option can speed some operations dramatically.</td>
 251                 </tr>
 252                 <tr>
 253                         <td align = "center"><tt>NSBackwardsSearch</tt></td>
 254                         <td>Performs searching from the end of the range toward the beginning.</td>
 255                 </tr>
 256         </table></blockquote></blockquote>
 257         See "Strings" for details on these options. Raises an <tt>NSInvalidArgumentException</tt> if any of the arguments are <tt>nil</tt>. Raises an <tt>NSRangeException</tt> if any part of <tt><i>range</i></tt> lies beyond the end of the string.
 258         @param set The set of characters to look for.
 259         @param mask Mask values determining how to search.
 260         @result Returns <tt>YES</tt> if the receiver contains only the characters.
 261  */
 262 - (BOOL)containsOnlyCharactersFromSet:(NSCharacterSet *)set options:(unsigned int)mask;
 263
 264 /*!
 265         @method containsOnlyCharactersFromSet:options:range:
 266         @abstract Test if a string contains only the characters from a set.
 267         @discussion Returns <tt>YES</tt> if the receiver contains only character from <tt><i>set</i></tt> within the range <tt><i>range</i></tt>, otherwise returns <tt>NO</tt>. The following options may be specified in <tt><i>mask</i></tt> by combining them with the C bitwise OR operator:
 268         <blockquote><blockquote><table border = "1" width = "90%">
 269                 <thead>
 270                         <th>Search Option</th>
 271                         <th>Effect</th>
 272                 </thead>
 273                 <tr>
 274                         <td align = "center"><tt>NSCaseInsensitiveSearch</tt></td>
 275                         <td>Ignores case distinctions among characters.</td>
 276                 </tr>
 277                 <tr>
 278                         <td align = "center"><tt>NSLiteralSearch</tt></td>
 279                         <td>Performs a byte-for-byte comparison. Differing literal sequences (such as composed character sequences) that would otherwise be considered equivalent are considered not to match. Using this option can speed some operations dramatically.</td>
 280                 </tr>
 281                 <tr>
 282                         <td align = "center"><tt>NSBackwardsSearch</tt></td>
 283                         <td>Performs searching from the end of the range toward the beginning.</td>
 284                 </tr>
 285         </table></blockquote></blockquote>
 286         See "Strings" for details on these options. Raises an <tt>NSInvalidArgumentException</tt> if any of the arguments are <tt>nil</tt>. Raises an <tt>NSRangeException</tt> if any part of <tt><i>range</i></tt> lies beyond the end of the string.
 287         @param set The set of characters to look for.
 288         @param mask Mask values determining how to search.
 289         @param range The range to limit the search to.
 290         @result Returns <tt>YES</tt> if the receiver contains only the characters.
 291  */
 292 - (BOOL)containsOnlyCharactersFromSet:(NSCharacterSet *)set options:(unsigned int)mask range:(NSRange)range;
 293
 294
 295 /*!
 296         @method componentsSeparatedByString:withOpeningQuote:closingQuote:singleQuote:
 297         @abstract Get an array of string componets.
 298         @discussion Returns an <tt>NSArray</tt> containing substrings from the receiver that have been divided by separator. The substrings in the array appear in the order they did in the receiver.
 299         @param separator The delimeter used to seperate the strings.
 300         @param openingQuote The string used to begin a quoted component, a component where the delimiter is ignored.
 301         @param closingQuote The string used to end a quoted component, a component where the delimiter is ignored.
 302         @param singleQuote The string used to quote a single character.
 303         @param flag Set to true if empty string are wanted.
 304         @result A <tt>NSArray</tt> of components.
 305  */
 306 - (NSArray *)componentsSeparatedByString:(NSString *)separator withOpeningQuote:(NSString *)openingQuote closingQuote:(NSString *)closingQuote singleQuote:(NSString *)singleQuote includeEmptyComponents:(BOOL)flag;
 307
 308
 309 /*!
 310         @method stringByReplacingString:withString:
 311         @abstract Create a new string by search and replace.
 312         @discussion <tt>stringByReplacingString:withString:</tt> creates a new string from the reciever by replacing all occurances of <tt><i>searchString</i></tt> with the string <tt><i>replaceString</i></tt>. If the string <tt><i>searchString</i></tt> is not found then the string returned will be identical to the reciever.
 313         @param searchString The string to replace in the reciever.
 314         @param replaceString The string to replace <tt><i>searchString</i></tt> with.
 315         @result A new string.
 316  */
 317 - (NSString *)stringByReplacingString:(NSString *)searchString withString:(NSString *)replaceString;
 318
 319 @end
 320
 321
 322 /*!
 323         @category NSMutableString(NDUtilities)
 324         @abstract Addition methods for <tt>NSString</tt>
 325         @discussion Additonal useful methods for <tt>NSMutableString</tt>, that can be used in general situations.
 326  */
 327 @interface NSMutableString (NDUtilities)
 328
 329 /*!
 330         @method prependString:
 331         @abstract Prepend a string.
 332         @discussion Adds the characters of <tt><i>string</i></tt> to the beginning of the receiver. <tt><i>string</i></tt> may not be <tt>nil</tt>.
 333         @param string The string to append.
 334   */
 335 - (void)prependString:(NSString *)string;
 336
 337 /*!
 338         @method prependFormat:
 339         @abstract Prepend a string format.
 340         @discussion Adds a constructed string to the beginning of the receiver. Creates the new string using <tt>NSString</tt>'s  <tt>stringWithFormat:</tt> method with the arguments listed. Raises an <tt>NSInvalidArgumentException</tt> if <tt><i>format</i></tt> is <tt>nil</tt>.
 341         @param format The format string to append, followed by values to insert.
 342   */
 343 - (void)prependFormat:(NSString *)format, ...;
 344
 345 @end